home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Tcl_Interp.man < prev    next >
Encoding:
Text File  |  1990-02-03  |  4.6 KB  |  135 lines
  1.  
  2.  
  3.  
  4. Tcl_Interp        Tcl Command Language Library         Tcl_Interp
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_Interp - client-visible fields of interpreter structures
  12.  
  13. SSYYNNOOPPSSIISS
  14.      ##iinncclluuddee <<ttccll..hh>>
  15.  
  16.      typedef struct {
  17.           char *_r_e_s_u_l_t;
  18.           int _d_y_n_a_m_i_c;
  19.      } Tcl_Interp;
  20.  
  21. _________________________________________________________________
  22.  
  23.  
  24. DDEESSCCRRIIPPTTIIOONN
  25.      The  TTccll__CCrreeaatteeIInntteerrpp  procedure  returns  a  pointer  to  a
  26.      Tcl_Interp  structure.   This  pointer  is  then passed into
  27.      other Tcl procedures to process commands in the  interpreter
  28.      and  perform  other  operations  on the interpreter.  Inter-
  29.      preter structures contain many many fields that are used  by
  30.      Tcl,  but  only two that may be read and written by clients:
  31.      _r_e_s_u_l_t and _d_y_n_a_m_i_c.  These fields are used  by  Tcl  command
  32.      procedures to return strings that form part of the result of
  33.      each command.  When Tcl_Eval returns, the string pointed  to
  34.      be  the  _r_e_s_u_l_t field will be used by Tcl_Eval's caller as a
  35.      return value or error message.
  36.  
  37.      The easiest way for command  procedures  to  manipulate  the
  38.      _r_e_s_u_l_t and _d_y_n_a_m_i_c fields is to call Tcl_Return;  Tcl_Return
  39.      will hide all the details of  managing  these  fields.   The
  40.      description  below  is  for those procedures that manipulate
  41.      the fields directly.
  42.  
  43.      Whenever a command procedure returns, it  must  ensure  that
  44.      the  _r_e_s_u_l_t  field  of  its interpreter points to the string
  45.      being returned by the command.  Normally, these strings  are
  46.      assumed  to  be  statically  allocated;   in  this case, the
  47.      _d_y_n_a_m_i_c field must be zero.  As an  alternative,  a  command
  48.      procedure  may  dynamically  allocate  its  return value and
  49.      store a pointer to it in _i_n_t_e_r_p->_r_e_s_u_l_t.  In this case,  the
  50.      command procedure must also set _i_n_t_e_r_p->_d_y_n_a_m_i_c to non-zero.
  51.      If _i_n_t_e_r_p->_d_y_n_a_m_i_c is non-zero, then Tcl will free the space
  52.      pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t before it invokes the next com-
  53.      mand.  If a client procedure overwrites _i_n_t_e_r_p->_r_e_s_u_l_t field
  54.      when _i_n_t_e_r_p->_d_y_n_a_m_i_c is non-zero, then it is responsible for
  55.      freeing the old _i_n_t_e_r_p->_r_e_s_u_l_t.  Once again, if clients  use
  56.      the  TTccll__RReessuulltt  procedure to manage these fields, they need
  57.      not worry about these issues.
  58.  
  59.      As part of processing  each  command,  TTccll__EEvvaall  initializes
  60.      _i_n_t_e_r_p->_r_e_s_u_l_t  and  _i_n_t_e_r_p->_d_y_n_a_m_i_c just before calling the
  61.      command procedure for the command.  The _d_y_n_a_m_i_c  field  will
  62.  
  63.  
  64.  
  65. Sprite v.1.0       Printed:  February 3, 1990                   1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. Tcl_Interp        Tcl Command Language Library         Tcl_Interp
  73.  
  74.  
  75.  
  76.      be  initialized to zero, and _i_n_t_e_r_p->_r_e_s_u_l_t will point to an
  77.      empty string.  Commands that do not  return  any  value  can
  78.      simply  leave  the  fields  alone.   Furthermore,  the empty
  79.      string pointed to by _r_e_s_u_l_t is actually part of an array  of
  80.      TTCCLL__RREESSUULLTT__SSIIZZEE  characters  (approximately 200).  If a com-
  81.      mand wishes to return a short string, it can simply copy  it
  82.      to  the  area  pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.  Or, it can use
  83.      the sprintf procedure to generate a short result  string  at
  84.      the location pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  85.  
  86.      If a command procedure calls a  lower-level  procedure  that
  87.      sets _i_n_t_e_r_p->_r_e_s_u_l_t and _i_n_t_e_r_p->_d_y_n_a_m_i_c (such as a recursive
  88.      instance of TTccll__EEvvaall), then the command procedure must reset
  89.      _i_n_t_e_r_p->_r_e_s_u_l_t if it wishes to return a value different than
  90.      that returned by the  lower-level  procedure.   As  part  of
  91.      resetting  _i_n_t_e_r_p->_r_e_s_u_l_t, it must free the space if _i_n_t_e_r_p-
  92.      >_d_y_n_a_m_i_c is set.  Once again, the easiest way to  make  sure
  93.      this gets done right is to call TTccll__RReessuulltt.
  94.  
  95.  
  96. KKEEYYWWOORRDDSS
  97.      dynamic, interpreter, result
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131. Sprite v.1.0       Printed:  February 3, 1990                   2
  132.  
  133.  
  134.  
  135.